Copyright: Copyright ©1998-2000 Dale Nurden, All Rights Reserved


Contents
TClockEx

TaskBar Clock Enhancement

For Microsoft Windows 95, 98 and NT

Version 1.4.2

Copyright ©1998-2000 Dale Nurden

All Rights Reserved

Contents

Contacting the Author

Copyright, License and Disclaimer

Acknowledgements

Getting Started

Introduction to TClockEx

What’s New in This Version

Installation

Removal

Installing Additional Windows Components

Features

Menu

Shortcuts

Calendar

Copy/Paste

Resources

Booth Mode

Control Panel

Custom Formats

Overview

Literal Text in a Custom Format

System-Defined Formats

Date Elements

Time Elements

Resource Elements

Special Elements

User-Defined Elements

Properties

Overview

Clock Page

Tooltip/Copy Page

Calendar Page

Menu Page

Advanced Page

About Page

Notes

Platform Notes

ISO8601 Week Numbers

Year 2000 Compliance

Technical Information

DDE Interface

TCSET.EXE

Troubleshooting

What to do if you discover a bug

Divide error

Resource elements do not work

CPU usage does not work

Flickering cursor

Please report bugs and send comments to the author.


Contacting the Author

The author and owner of TClockEx is Dale Nurden.

WWW:	http://users.iafrica.com/d/da/dalen

Email:	dalen@iafrica.com
dalen@rcis.co.za

Mail:	Dale Nurden
14 Willow Crescent
Pinetown 3610
South Africa

Be assured that I personally read every email that I receive, but sometimes it takes a week or two to reply because of the volume of email and the limited time I have to deal with it.  Whenever possible, I try to reply to every email personally.

Suggestions

If you have suggestions that you feel would improve TClockEx, include them with your comments.  Please don’t feel compelled to think up suggestions.  My intention is to keep this program small and simple, focusing on things that one would expect from a clock.  For example, you wouldn’t expect a clock to shut Windows down, so don’t ask me to include a shutdown option in the menu.  It doesn’t make sense.

If you like this program or find it useful, please encourage me to continue development by sending a postcard with your comments and suggestions.  (If sending postcards means having to go out into the sunlight, then email will do.)

If you really like this program, I’m rather partial to T-shirts – X-large size (hint hint!).


Copyright, License and Disclaimer

TClockEx is Freeware.  You may happily (or unhappily if you prefer) use this software on any number of computers for as long as you like, and you don’t have to pay me a cent.  Really!  There are no crippled features for registered users only, no time delays and no stupid nag screens for you to hack.  I use other people’s Freeware, and this is my contribution in return.

If that makes you nervous and you really want to send me something in return, send me a nice T-shirt from your home town.

All that said, TClockEx is not Public Domain software.  I allow the free distribution of the software, but I retain ownership and copyright of the software and its source code in its entirety.

You may use and/or distribute this software only subject to the following conditions:

-	You may not modify the program or documentation files in any way.

-	You must include all the files that were in the original distribution.

-	You may not sell the software or charge a distribution fee, except to recover the media costs.

-	You may not remove my name or copyright notification, and you may not claim to be the owner or author of this software (because you are not!).

-	You understand and agree with this license and with the disclaimer printed below.

This software may be bundled and distributed together with other products, but the same conditions apply.  You do not need to seek my permission first.  (But a note telling me about it would be nice.  A free copy of the bundle would be even nicer!)

Some people have very kindly recommended TClockEx to their friends and colleagues.  Thank you for doing that, but do please also direct them to my home page, so they know where to look for upgrades.  This also applies if you’re submitting TClockEx for a magazine review.

Disclaimer

TClockEx uses undocumented operating system features to perform some of its functions.  While every care has been taken to ensure that it is safe and non-destructive, you use this product entirely at your own risk.  The author will not be held responsible or liable for any damages resulting from your use, misuse, or inability to use this product.  The platform notes have a little more to say about forward-compatibility issues.

If you do not agree with this disclaimer or the above conditions of use, you should not use this product.  Buy a wristwatch instead!

Dale Nurden

February 2000


Acknowledgements

I’ve received literally hundreds of emails from well-wishers and appreciative users, as well as a few postcards.  My thanks go to everyone who writes to compliment me and suggest ideas for future improvements (many of which have already found their way into TClockEx).  My continued development of this project has been directly encouraged by the overwhelming response I have received.  Despite a number of suggestions, TClockEx remains completely free software.

I am delighted to have been awarded one of nine “Winner 98” prizes from the WinFiles.Com shareware website, and so soon after the release of TClockEx (only a couple of months).  TClockEx has also featured in a number of online publications such as those of ZDNet and PC Magazine, and probably a whole bunch I’m not even aware of.

Special thanks go to Jim Freeman in Canada, who sent me a spare copy of Windows NT he had lying around so that I could test TClockEx with Windows NT and iron out the problems.  Also, to the folks who were kind enough to send me T-shirts from their home towns.


Introduction to TClockEx

TClockEx is a smart little program that enhances the clock that is built into the Windows 95, 98, NT and 2000 taskbar.  Now it is possible to see the date as well as the time on the taskbar in one glance, and with any format you like.  Many people have wondered why this wasn’t built into the clock to begin with.

I originally wrote TClockEx out of frustration with not being able to see the date easily.  Since the first release I have added new features after encouragement and requests from people with similar feelings.  I’ve seen other programs try to address the date issue by putting little windows in the corners of the screen, by changing the title bar of the active window, and so on.  Those ideas didn’t really appeal to me because they became intrusive and took up valuable screen space, or just got in the way.  Some programs even try to use a series of icons in the tray to display the date graphically.  Ugh!

TClockEx is my solution to the problem that should never have been.  It doesn’t try to make its own clock display.  Instead, it hooks right into the operating system and enhances the original clock itself.  So what you’re getting isn’t “Just Another Clock”, it’s the original Windows clock – enhanced.  If you’re the curious type, you can find out how in the technical information.

I originally intended TClockEx to be a small and simple utility without too many features to get in the way and slow things down.  So far I’ve resisted most temptations, but a few extra goodies have appeared along the way after requests from users or ideas of my own.


What's New in This Version

What’s New in This Version

These changes, from version 1.3.3, are included in TClockEx version 1.4. These are in addition to many less significant changes.  For a more complete change history please refer to the TClockEx home page.  If you would like to be notified when new versions are released, please send email.

New:

-	User-defined elements, may be accessed programmatically by DDE.

-	Date ordinal element “#” (eg. 1st, 2nd, 3rd, etc.) – English only.

-	Swatch Internet time element “@”.

-	“Booth mode” prevents people from changing the properties once they are set.

-	Control Panel icon for accessing TClockEx properties.

-	Hotlinks to author’s home page and email in the properties.

Improved:

-	Tooltip can display multiple lines. (Probably needs >= IE3 for this.)

-	CPU monitoring can be disabled if not used.

-	Clock click/double-click action can be changed.

-	Calendar window can remain open without being “topmost”, and can return to the previously selected month instead of always starting with the current month.

-	Calendar week can begin on any day of the week.

-	Calendar font option.

Changed:

-	Calendar range is limited to years 1601 – 3999 because some people were too curious… so yes, TClockEx is Y3k compliant!

-	Properties window rearranged and new pages added for extra options.

-	Calendar options moved from menu to the properties window.

Bugs fixed:

-	Daylight savings transitions should work properly. (I hope – we don’t have daylight saving in South Africa.)

-	Day-of-year number (Julian date) is calculated correctly during February in leap years.

-	TClockEx will co-exist with TraySaver B10.

-	Properties window appears in the correct position and checks that it is actually visible.

-	Closing some applets such as Notepad no longer causes the help to disappear.

-	Clock panel size adjusts correctly when the date changes.


Installation

TClockEx is distributed in a single self-installing executable file named either TCLOCKEX.EXE or TCLEXnnn.EXE, where “nnn” is the version number (e.g. “TCLEX142.EXE” for version 1.4.2).  There is also a non-self-installing distribution package named TCLOCKEX.ZIP, which is smaller to download, but takes more effort to install and lacks the control panel module.  If you don’t know what to do with ZIP files, please use the EXE version.

To install, simply run the distribution file TCLOCKEX.EXE and follow the prompts.  You will be asked for a folder to install into, and in most cases you can just use the default.  When the installation is complete, you will find an icon for TClockEx in your Start menu, and you can use that to set TClockEx up for the first time.

TClockEx loads itself automatically when Windows starts up.  An option to disable this feature is provided in the advanced properties.  There is no need to put a shortcut into the Startup menu.

If you are upgrading from a previous version, you may install the upgrade directly over the older version to preserve your settings.  Make sure that TClockEx is not running when you install the upgrade.


Removal

To uninstall, the usual method for Windows 95 programs applies – go to “Add/Remove Programs” in the control panel, and look for TClockEx in the list.

TClockEx must not be running when you uninstall, otherwise parts of the program may be left behind.  To shut TClockEx down, right-click on the clock and choose “Exit TClockEx” from the menu.


Installing Additional Windows Components

TClockEx includes the ability to report on CPU and resource usage, however for these features to work requires two optional Windows components that may or may not be already installed on your computer.

The CPU usage indicator requires the existence of the Windows System Monitor, which is included on the Windows 95/98 CD-ROM.  The resource indicators require the existence of the Windows System Resource Meter, also on the CD-ROM.  If either of these components is missing you can install it from the control panel:

1.	From the Control Panel, double-click Add/Remove Programs.

2.	Click the Windows Setup tab.

3.	Scroll down the list and click on System Tools, the click the Details button.

4.	In the new window that appears, scroll down the list and make sure that both System Monitor and System Resource Meter are checked.  (If they are checked already, then everything you need is already installed.)

5.	Click OK to install the components.  Windows may ask for the original installation disks or CD-ROM.

6.	Click OK to finish.

After doing this you will need to restart TClockEx, after which time the CPU usage and resource indicators should function properly.

Windows NT/2000 only:
Windows NT/2000 includes neither of these two components.  As a result, the CPU usage and resource features do not work.  Resources are meaningless under Windows NT/2000 anyway.


Menu

Some of TClockEx’s features may be accessed through the context menu, which is activated by right-clicking on the clock panel.  These are in addition to the usual options provided by the operating system, such as changing the time and date, rearranging windows on the desktop and so on.  (Apparently someone thought that rearranging windows was something a clock ought to be able to do, but changing the appearance of the clock was not.)

TClockEx adds these options to the context menu:

Exit TClockEx	Terminates TClockEx and restores the standard taskbar clock.

TClockEx Help	Displays the help index.

TClockEx Properties	Opens the properties window.

Calendar	Opens the calendar window.

Copy	Activates the copy/paste function.

Some of these options can be set up to be triggered simply by clicking or double-clicking on the clock panel.  To do this, have a look at the menu properties.

Note:  If Booth mode is selected, some of these options will be removed from the menu.

Windows NT only:
You must use the mouse to select items from the context menu.  You can use the keyboard, but you will find that hitting <ENTER> doesn’t work, due to a problem with Windows NT.


Shortcuts

Certain features may be set up to be activated with a single or double click on the taskbar clock panel.  Do this from the menu properties.

Shortcut actions:

Windows default	Performs the usual action for the standard taskbar clock.

Do nothing	Clicking or double-clicking has no effect.

TClockEx Properties	Opens the properties window.

Calendar	Opens the calendar window.

Copy	Activates the copy/paste function.

Note that the “TClockEx Properties” action is not affected by the booth mode option.

Single Click	Double Click
Windows default:	Nothing	Adjust Date/Time
TClockEx default:	Calendar	Copy/Paste


Calendar

The calendar shows a month at a time, with the present day highlighted for easy reference.  Activate the calendar by choosing Calendar from the menu, or by clicking on the clock panel.  The range of the calendar is from 1601 to 3999 inclusive. (Yes, TClockEx is Y3k compliant!)

While the calendar is visible, the following keys may be used:

PgUp	Previous month.

PgDn	Next month.

Ctrl + PgUp	Previous year.

Ctrl + PgDn	Next year.

Home	Return to the present year and month.

Some aspects of the calendar, such as the display font, may be customised in the calendar properties.  It is also possible to highlight certain days and change the first day of the week.

Other options determine how and where the calendar window appears on the screen:

-	Remember last position:
Causes the calendar to return to its previous screen position each time.

-	Close when not active:
Closes the calendar when another window is activated.  If this option is not selected, the calendar will remain open until closed by the user.

-	Stay on top:
Causes the calendar window to remain on top of all other windows, even when not the active window.  This has little effect if the “Close when not active” option is selected.

-	Show week numbers:
Includes week numbers (determined according to ISO8601) on the calendar.  Weeks are always numbered beginning with Monday, regardless of the day chosen to start the calendar week.  This is in line with ISO8601.

-	Remember selected month:
Causes the calendar to return to the previously selected year and month, instead of  always starting with the present date.


Copy/Paste

The copy/paste feature copies information onto the Windows clipboard so that it can be pasted into another application.  Activate this feature by choosing Copy from the menu, or by double-clicking on the clock panel.

The information that is copied can be either the same as the chosen clock format, or a specially customised format, set up in the tooltip/copy properties.


Resources

Although the main purpose of TClockEx is to provide time and date functions, the ability to monitor CPU, memory and resource usage is often invaluable.  TClockEx has special display elements that expand to report CPU usage, memory load, and system resources.  Resource settings can also be found in the advanced properties.  Note that there is only limited support for these features under Windows NT/2000.

The CPU usage indicator is a percentage value that indicates the amount of time the CPU spends in the operating system’s idle loop.  This can also be displayed a coloured indicator line appearing directly above the taskbar clock.  Note that most 16 bit applications and some 32 bit applications may interfere with this, causing the indicator to report 0% or 100% usage all the time.  It is also possible that two different applications, both monitoring CPU usage, may interfere with each other.  CPU monitoring is not currently possible on Windows NT/2000.

Memory load is a percentage indication of the system’s overall use of available memory, including both physical RAM and virtual memory on disk.  This behaviour may be modified in the advanced properties.  It is common for this value to remain between 33% and 50%, even when no applications are loaded, because of the way Windows caches and optimises memory usage.  On Windows NT/2000 the memory load only includes physical RAM usage.

System, user and GDI resources are percentage indications of the overall use of these specially-reserved memory areas in Windows 95/98.  When these numbers get too low you must close a few applications down, otherwise you run the risk of all sorts of silly and unusual things happening to your computer.  These values are meaningless in Windows NT/2000, which is a Good Thing!


Booth Mode

Booth mode is a special feature intended for system administrators who wish to install TClockEx on their users’ computers but prevent the users from making changes to TClockEx’s properties.  Booth mode is activated from the menu properties.

When booth mode is activated, these items are removed from the menu to prevent authorised changes:

Exit TClockEx

TClockEx Help

TClockEx Properties

However the user still has access to the calendar and copy/paste features.

In addition, the control panel icon is removed.

Accessing properties in booth mode

In booth mode, the properties window may be accessed by running the TClockEx loader program, for example from the Start menu.  The administrator should therefore also remove the TClockEx icon from the Start menu, and take any other steps necessary to limit access to the TCLOCKEX.EXE program.

Be aware that if a single or double-click mouse action has been set to activate the properties, this is not suppressed by booth mode.

Security Note:
Booth mode is intended to discourage users from making changes to the TClockEx properties, but it should not be considered a foolproof method of security.


Control Panel

TClockEx adds a new “Clock” icon to the Windows control panel.  Double-clicking the icon activates the TClockEx properties window.

This feature can be disabled in the advanced properties, and is disabled automatically in booth mode.

The control panel module is only included with the self-installing distribution package.


Custom Formats

TClockEx generates output for the clock, tooltip and copy/paste function from user-defined format strings.  A format string comprises one or more display elements that represent pieces of information, such as the hour or the month.  This may seem a little awkward at first, but it offers the greatest degree of flexibility when it comes to designing a format that suits your needs.  To assist, a popup menu of all the display elements is included, along with a few example formats that can be modified.

For example, the format string “d MMMM” would produce “10 December” because “d” is replaced with the current day of the month, and “MMMM” is replaced with the full month name.

All the display elements are grouped:

Literal Text

System-Defined Formats

Date Elements

Time Elements

Resource Elements

Special Elements

User-Defined Elements

When you choose an element from the menu, TClockEx inserts it into the format string at the cursor position, replacing any text that is selected.

Limitations

The maximum length of any format string is 119 characters including all display elements.  After all display elements have been expanded, the maximum displayable string length is 239 characters.  In addition, the tooltip has a maximum length of 80 displayable characters imposed by the operating system.

Hint: TClockEx’s formatting codes are as language-sensitive as the operating system, so if you have a French version of Windows, for example, you will see French weekday and month names.


Literal Text in a Custom Format

Any text in a format string that is not part of a valid display element, will be displayed as-is.  You can force TClockEx to treat any part of the string literally, ignoring any display elements it contains, by enclosing it in single quotation marks (‘ ’).

Using single quotation marks is often necessary when you want to display a label alongside an element.  For example, if you wanted to produce the output “Month = December”, the following would be the result with and without the use of single quotation marks:

Format	Produces

“Month = MMMM”	“10onA8 = December”

“’Month’ = MMMM”	“Month = December”

The reason for the discrepancy in the first case is that TClockEx interprets the “M” in “Month” as a format element representing the month number.  Similarly it interprets “t” and “h” as elements representing “AM/PM” and the hour, respectively.


System-Defined Formats

System-defined formats are determined by the operating system from the current system or logged-on user settings, and may be adjusted in the control panel.

These display elements are case-sensitive:

f	System-defined short time (without seconds)

ff	System-defined long time (includes seconds)

fff	System-defined short date

ffff	System-defined long date


Date Elements

These display elements are case-sensitive:

d	Day

dd	Day (two digits)

ddd	Day name (abbreviated)

dddd	Day name (full)

#	Day ordinal (1st, 2nd, 3rd, etc. – does not include the day number)

M	Month

MM	Month (two digits)

MMM	Month name (abbreviated)

MMMM	Month name (full)

yy	Year (two digits)

yyyy	Year (four digits)

gg	Period/era (not used with Western calendar systems)

w	Week number (determined according to ISO8601)

ww	Week number (2 digits)

D	Day of year

DDD	Day of year (3 digits)


Time Elements

These display elements are case-sensitive:

h	Hour (1 - 12)

hh	Hour (01 - 12)

H	Hour (0 - 23)

HH	Hour (00 - 23)

m	Minute

mm	Minute (two digits)

s	Second

ss	Second (two digits)

t	A/P *

tt	AM/PM *

@	Swatch Internet time

zz	Time zone bias (hours difference from UTC)

ZZ	Time zone name

The time zone bias is the time difference in hours and minutes between the current time zone and Universal Co-ordinated Time (UTC, formerly GMT).  Time zones east of UTC are positive, while those west are negative.  For example, South Africa is +0200, two hours ahead of UTC.

The time zone name is the full name of the time zone, as reported by the operating system.  Windows has no provision for abbreviated time zone names, so TClockEx is not able to display them.  Daylight saving is automatically factored into the clock display and time zone when appropriate.

* The AM/PM indicator may be changed (for example, to “am” or “pm”) in the control panel.


Resource Elements

These display elements are case-sensitive:

r	Physical RAM not in use (kilobytes)

R	Physical RAM not in use (megabytes)

L	Memory load percentage

LL	Memory load percentage (two digits)

S	System resources % available

SS	System resources % available (two digits)

U	User resources % available

UU	User resources % available (two digits)

G	GDI resources % available

GG	GDI resources % available (two digits)

C	CPU Usage %

CC	CPU Usage % (two digits)

There are some limitations to using these displays elements.  They may require the installation of additional Windows components, and some of these elements are not fully supported in Windows NT/2000.


The CPU usage indicator is a percentage value that indicates the amount of time the CPU spends in the operating system’s idle loop.  This can also be displayed a coloured indicator line appearing directly above the taskbar clock.

Note that most 16 bit applications and some 32 bit applications may interfere with this, causing the indicator to report 0% or 100% usage all the time.  It is also possible that two different applications, both monitoring CPU usage, may interfere with each other.

CPU monitoring is not currently possible on Windows NT/2000.


Memory load is a percentage indication of the system’s overall use of available memory, including both physical RAM and virtual memory on disk.  This behaviour may be modified in the advanced properties.

It is common for this value to remain between 33% and 50%, even when no applications are loaded, because of the way Windows caches and optimises memory usage.

On Windows NT/2000 the memory load only includes physical RAM usage.


System, user and GDI resources are percentage indications of the overall use of these specially-reserved memory areas in Windows 95/98.  When these numbers get too low you must close a few applications down, otherwise you run the risk of all sorts of silly and unusual things happening to your computer.

These values are meaningless in Windows NT/2000, which is a Good Thing!


Special Elements

TClockEx allows format strings to run over more than a single line, by using the “|” element (a vertical bar) to act as a line break.  Everything that follows this display element will be moved to the next line.

The clock display is usually centred, but you can left- or right-align it by adding a positioning element, “<” or “>” respectively, at the beginning of the line.  It will be ignored if placed anywhere other than the beginning of the line.  When choosing these elements from the menu, TClockEx inserts them at the correct position automatically.  Positioning elements operate on a single line only, so it is possible to align one line differently from another.

If two similar display elements must be placed together, a hidden separator element “~” (tilde) may be used to separate them to avoid misinterpretations.  This element is ignored except as a separator.  For example, the format “dddd” produces the full weekday name “Thursday”, whereas with a hidden separator, “d~ddd”, it produces “10Thu”.

Hint: Multi-line format strings may be used for the clock, tooltip and copy/paste function.


User-Defined Elements

TClockEx supports the use of user-defined display elements, which may be accessed programmatically by third-party applications to display additional information not provided by TClockEx in the taskbar clock panel.

User-defined elements are defined in a format string by surrounding the name of the element with “%” symbols.  For example, if a user-defined element were named “Username”, then the format string might be similar to this: “’User = ’%USERNAME%”.  Note that the label portion of the string (“User = ”) is enclosed in single quotes to prevent it from being interpreted as a display element, and the user-defined element is enclosed in “%” symbols.  User-defined elements that have no value are ignored.

User-defined element names are not case-sensitive and have a maximum length of 8 alphanumeric characters.  Elements may be assigned, deleted or reassigned at any time, but no more than 16 may be defined at any one time.

The TCSET.EXE utility may be used to assign user-defined element values.


Properties

The properties window is the heart of TClockEx that lets you decide what you want to see in the taskbar clock.  The properties window appears the first time TClockEx runs, and thereafter only when you call for it (by either using the menu or running TCLOCKEX.EXE again).  TClockEx remembers the last page that was active and reopens to that page.

See more information about each of the property pages:

Clock Page

Tooltip/Copy Page

Calendar Page

Menu Page

Advanced Page

About Page

Hint: The properties are stored on a per-user basis in the registry, so if your computer is set up with more than one user profile, each user’s preferences will be retained individually.  This also means that you need to set up TClockEx for each new user that uses your computer.


"Clock" Property Page
“Clock” Property Page

Click on the image for more information about specific controls on this page.

Use the settings on this page to modify the appearance of the taskbar clock.  Use one of the sample formats or build your own custom format by clicking “Format Elements” and picking display elements from the menu.  If you select part of the format string and pick a display element, it will replace the selection portion section.  The only exception is if you choose “Literal Text”, the selected section will instead be enclosed in single quotation marks.

Example:

 “d MMM, HH:mm (dddd)”    --    “20 Dec, 18:56 (Monday)”

Colours and Fonts

The default font and colour options make TClockEx look the same as the standard taskbar clock, but you can choose your own colours and font if you prefer.  Actually, the default font is the system menu font, which is usually, but not always, the same as the standard taskbar clock.

There is a caveat however: TClockEx does not check that the font you choose will fit into the space allocated for the clock.  It’s up to you to make sure you pick a font that fits nicely.  You need to pay special attention to this if you use a multi-line display format.


"Tooltip/Copy" Property Page
“Tooltip/Copy” Property Page

Click on the image for more information about specific controls on this page.

Similarly to the clock display, you can customise the format of the tooltip, which appears when the cursor hovers over the clock for a few seconds.  Windows normally displays the date in the tooltip, but TClockEx lets you display anything you like.  If you leave the format blank, there will be no tooltip at all.  The tooltip can now also display multiple lines (this may require an updated DLL file from Microsoft), but there is a limit of 80 characters imposed by the operating system.

The “Copy/Paste” feature, accessible from the menu, lets you paste the time and date into another application via the clipboard.  TClockEx can either simply copy the clock or tooltip onto the clipboard, or you can define your own special format that is used just for copying.  A shortcut for this feature may be activated by clicking or double-clicking the clock panel.


"Calendar" Property Page
“Calendar” Property Page

Click on the image for more information about specific controls on this page.

The options on this page relate to the calendar feature built into TClockEx.  The calendar shows a month at a time, and has options to include week numbers (determined according to ISO8601), highlight weekends, and change the first day of the week.  You can now also choose a font for the calendar.

The calendar may be accessed from the menu, or through a shortcut activated by clicking or double-clicking the clock panel.

Note that although any day can be made the beginning of the week, week numbers always begin on Mondays, in line with ISO8601.

Hint: If the calendar window is already visible, some of these options may not be effective until it is closed.


"Menu" Property Page
“Menu” Property Page

Click on the image for more information about specific controls on this page.

The options on this page relate to the menu that appears when you right-click on the clock panel.  Shortcuts to some of TClockEx’s features may be activated by certain mouse actions, such as clicking or double-clicking the clock panel.  The default single-click action is to activate the calendar feature; the default double-click action is to activate the copy/paste function.

Booth mode is a special secure mode that prevents users from changing TClockEx’s settings.


"Advanced" Property Page
“Advanced” Property Page

Click on the image for more information about specific controls on this page.

This page contains special resource options that advanced users might find useful.  The resource indicators are coloured lines that appear above and below the clock display to give a continuous visual indication of CPU and memory usage.  In both cases, the longer the line, the greater is the estimated usage.  These are refreshed at one-second intervals.

The memory load is a percentage indication of overall memory usage by the system for all applications.  Alternatively, there is an option to assess only the physical RAM usage when determining the memory load.  (This also affects the memory load display element.)  With Windows 95’s improved memory handling, this indication may not be of much value, but it’s there if you’re interested and you can switch it off if you’re not.

TClockEx now has the ability to display an icon in the control panel that allows access to the properties.  This can be controlled from here.

Windows NT/2000 only:
-	The CPU usage option is disabled because Windows NT/2000 uses a different method to assess CPU usage, which TClockEx cannot access (yet!).
-	The memory load always assesses only the physical RAM usage; Windows NT/2000 does not provide an overall memory usage assessment.


"About" Property Page
“About” Property Page

Click on the image for more information about specific controls on this page.

This page displays information about the version of TClockEx currently running, and provides links to the author’s home page and email.


Platform Notes

What computer does this work on?

TClockEx works correctly on Windows 95, 98, NT and 2000, with or without the various upgrades and service packs.  Previously I did not have access to Windows NT so I was unable to test that platform or fix the bugs that showed up, but now thanks to a happy TClockEx user I now have a copy of NT, which proved invaluable for fixing the bugs.  TClockEx definitely does not work with Windows CE or anything earlier than Windows 95, such as Windows 3.1 (which didn’t even have a clock to speak of).

Forward Compatibility Issues

Because of the way TClockEx goes about its business, hooking into the operating system and using undocumented operating system features, there can be no guarantee that it will continue to work with newer, yet-to-be-released, versions of Windows.  This is unavoidable.  I will endeavour to update TClockEx whenever necessary and possible.

Please also read the license and disclaimer that applies to this product.


ISO8601 Week Numbers

TClockEx adheres to the ISO8601 standard for determining week numbers.

Briefly, ISO8601 states that weeks begin on a Monday, and week #1 of any year is the first week that contains January 4.  That means that in some cases January 1, 2 and 3 could fall into week #52 or #53 of the previous year.  Likewise, the last few days of December could fall into week #1 of the following year.  If you don’t like this, take it up with the ISO.

I realise that many people use different methods to determine week numbers, but it seems that everyone and his grandmother has his own special method.  Hey, this is why we have standards!  I’ll try to support one or two of the more common alternatives in a future version.


Year 2000 Compliance

TClockEx is as year-2000-compliant as your operating system.  All it does is display whatever the operating system tells it to.  No panic here.


Technical Information

How’d he do that?

Curious to know how TClockEx works?  Well I’m not going to go into any great depth in explaining the whole process, but since I like to know how things work, I thought I might explain it.  This is intended mainly for curious programmers.  The source code for TClockEx (Borland C 5.02 with Win32 APIs) is not freely available, but if this discussion does not satisfy your curiosity, contact me and maybe we can figure something out.

Hooking into the taskbar clock to accomplish what we want to do is not really all that difficult.  It is a technique called subclassing, which allows us to intercept messages that are destined for another window and examine them ourselves.  For TClockEx, we want to intercept the paint messages that are sent to the taskbar clock whenever it needs to be drawn on the screen.  We also want to intercept a few others that Windows sends, for example to resize the clock window so that it will fit our expanded clock display.  A couple of the messages we need to intercept are undocumented.  I used Winsight to find them.

The biggest hurdle is the fact that Windows doesn’t allow one process to subclass a window that belongs to a different process.  Which means that in order to subclass the clock window, we need to find some way of executing our own code in the context of the other process.  Fortunately there is a way.  Windows has a nifty facility called a “hook”, which is vaguely similar to a subclass except that it can intercept more than just messages that are sent to windows, and it can do a bunch of other useful things (such as recording macros).  But for us, the value of a hook lies in the fact that the hook function (which our process provides), gets executed in the context of the hooked process, not our own.  This is exactly what we want: our code executing within the context of another process.

So here’s how it all works: Our program (TCLOCKEX.EXE, which I’ll call Process A), installs a hook into Windows Explorer (which is what actually owns the taskbar clock, and which I’ll call Process B).  Our hook function will get triggered as soon as Process B receives any message from the system (it doesn’t matter which message it is).  I send a resize message (WM_EXITSIZEMOVE) to the clock window to nudge it along a bit.

Process B receives a message and so executes our hook function in its own context.  The hook function installs a subclass on the taskbar clock window, and then signals that it has done so.  In the mean time, Process A has been waiting for notification (via a global synchronisation object) that the subclass has been installed successfully.  Upon receiving the notification, Process A removes the hook that it had installed, and then terminates.  Note that Process A was simply a loader that got everything going, but once TClockEx (TCLOCKEX.DLL) has subclassed itself into Windows Explorer, Process A was no longer needed and actually terminated.  Also note that the hook function was simply a means to install the required subclass, after which it too was no longer needed.

Finally, we use WM_COPYDATA messages to pass setup information (such as the time and date format) from our properties dialog (which runs in the context of Process A) to the subclassed clock window in Process B.

How do we know which window is the taskbar clock window?  Well, it is a child window of the system tray, which in turn is a child of the taskbar itself.  So we first have to find the taskbar, by looking for a window with the class “Shell_TrayWnd”, then the system tray window (class “TrayNotifyWnd”), and then finally the clock window (class “TrayClockWClass”).  Simple, huh?

What about the context menu?

Until version 1.2.0, that’s where the complication ended.  But the one feature that was most lacking was the ability to configure TClockEx by clicking on an option in the clock’s context menu.

To add my item, “TClockEx Properties”, to the context menu, I subclassed the taskbar itself (remember, we are also subclassing the clock window, which is a child of the taskbar), and looked out for WM_INITMENU messages, which the system sends just before it makes a menu visible.  WM_INITMENU contains the handle of the menu, and we can use that to add extra items before the menu is displayed.

Adding items to the context menu is easy.  Knowing when the user clicks our items is not!  A Win32 API programmer will know that the system is supposed to send WM_COMMAND when the user clicks on a menu item.  Well it doesn’t happen with the taskbar’s context menu.  Play around with Winsight and see for yourself.  Windows Explorer goes through all the motions with WM_INITMENU, WM_INITMENUPOPUP and WM_MENUSELECT, but when the user actually clicks on something… nothing!

To catch the menu item click, I subclassed the menu itself (class “#32768”), and watched for two undocumented messages that I observed (again with Winsight) were sent when a menu item was chosen - one for mouse clicks and the other for keyboard selections.  I then checked that the item being clicked was in fact our item (we don’t want to mess with any of the others), and used that to trigger our Properties window.

Finally, just for good measure I added an owner-drawn menu item that paints a bitmap to give the context menu a pretty label down the left-hand side (and an option to switch it off, for the purists).


Winsight

A programming tool supplied with the Borland C++ compiler (and others) that shows what messages are being sent around the system.


DDE Interface

TClockEx has provision to display user-defined elements in the various format strings.  User-defined display elements can display any information provided by a third-party application, and may be accessed programmatically using dynamic data exchange (DDE).

A third-party programmer may use the following information to build an application that interacts with TClockEx.  A sample program, TCSET.EXE, is included in the TClockEx distribution, and source code is available separately from the author.

DDE service name: TCLOCKEX

DDE topic: SYSTEM

This topic is required by the system, and returns information about the DDE server. The following items are recognised:

FORMATS	Returns a list of supported formats (currently only “TEXT”).

STATUS	Returns the status of the DDE server (“Ready”).

HELP	Returns help information.

SYSITEMS	Returns (this) list of supported items for the “SYSTEM” topic.

TOPICS	Returns a list of supported topics.

VERSION	Returns the version number of TClockEx (“1.4.1”).

DDE topic: USERELEMENT

Allows the value of user defined elements to be set.  This topic may only be used with DDE transactions of type XTYP_POKE.

The item is the name of the user-defined element, with a maximum length of 8 alphanumeric characters.  The item data is the value to which the item will be set.  If the data is blank, the named item is deleted.  There can be a maximum of 16 user-defined elements defined at any one time.


TCSET.EXE

TCSET.EXE is a Win32 command-line utility program that may be used to assign the values of user-defined display elements.  This is a free utility, and the source code is available from the author for developers who would like to incorporate its features into their own products.

Usage of TCSET.EXE is as follows:

TCSET element=[value] […]

Element is the name of a user-defined element.  This is not case-sensitive.

Value is the value to assign to the named element.  If the value is blank, the named element is deleted.

If an element name is already assigned, the new value will replace the older value.  Otherwise a new element will be created with the specified value.  The element name has a maximum length of 8 alphanumeric characters and may not include spaces.  No more than 16 elements may be defined at the same time.

More than one element may be assigned simultaneously by separating each argument by one or more spaces.  If the value includes a space, then the entire argument, including the element name, must be quoted.

The value of environment variables can be can be captured by specifying the name of the environment variable as the value, and enclosing it in “%” symbols.  For example, “TCSET tmp=%tmp%”.

Examples

TCSET user=Fred

Sets element %user% to “Fred”.

TCSET “name=Foo Bar”

Sets element %name% to “Foo Bar”.  The entire argument must be quoted because of the space in its value.

TCSET temp=%temp%

Sets element %temp% to the value of the environment variable named TEMP.

TCSET system= userid=Bob dept=Sales

Deletes element %system% and sets elements %userid% and %dept% to “Bob” and “Sales” respectively.


What to do if you discover a bug

Every effort has been made to eliminate bugs from this product.  However you may be lucky enough to spot the one or two that stowed away even despite my best efforts.  If you discover a bug, please report it to me and try to include some information that would allow me to duplicate the problem.  It’s very difficult to fix a problem when all I have to go on is, “your program keeps crashing!”

Important note: Before reporting a bug, please first check the list of known issues on the TClockEx home page to make sure it has not already been reported by someone else.


What to do if you get a "Divide Error"

Troubleshooting: Divide error

If you get a “Divide Error” while attempting to access TClockEx Properties, it means that you have an old version of one of the Windows system files, COMCTL32.DLL.  You can download an updated version, which fixes this and a few other problems not related to TClockEx, from Microsoft’s website.

Direct download of the update file: Click to go there

http://support.microsoft.com/download/support/mslfiles/COM32UPD.EXE

For more information about this update (Microsoft Knowledgebase): Click to go there

http://support.microsoft.com/support/kb/articles/Q165/4/87.asp

Once you have downloaded the update file, run it by double-clicking on its icon in Windows Explorer.  You will be required to restart Windows during the installation.

Special thanks to everyone who assisted in tracking down this bug by sending in debug reports from the previous version of TClockEx.  The special debug routines that were added for this purpose have been removed in later versions.


Resource elements do not work

Troubleshooting: Resource elements do not work

Resource elements in a format string will only work with Windows 95/98 if the Windows Resource Meter applet is installed on your computer.  If it is not installed the system (“S”), user (“U”) and GDI (“G”) resource elements will always display a value of zero.

TClockEx uses RSRC32.DLL, which is included with the Resource Meter, to determine these values.  On some computers this may not be installed by default, in which case you will need to follow these instructions to install it.

Windows NT/2000 only:
System, user and GDI resources are meaningless in Windows NT/2000, so these elements will never work with the Windows NT/2000 operating system.


CPU usage does not work

Troubleshooting: CPU usage does not work

CPU monitoring with Windows 95/98 may only be possible if the Windows System Monitor applet is installed.  If necessary, follow these instructions to install it.  This will affect both the CPU usage resource element (“C”) and the CPU usage indicator line.

Windows NT/2000 only:
CPU monitoring is not currently possible on Windows NT/2000.  This will be added in a future version of TClockEx.


Flickering cursor

Troubleshooting: Flickering cursor

It has been reported, though I have not observed this behaviour myself, that TClockEx causes the mouse cursor to flicker at one-second intervals on some computers.  Since I cannot duplicate this problem I cannot fix it!

I suspect that this is related to the display adapter and/or drivers, especially since the majority of complaints appear to involve display adapters based on S3 chipsets.  My development computer also has an S3 display adapter, but is not affected.


The Middle of the Help File

Welcome to the middle of the help file!

This is what happens when a programmer also writes the docs.


Determines the clock format, comprising a number of display elements representing various types of information.

Type the desired format string or click “Format Elements” to pick display elements from a list.

Example:

MMMM d#,  yyyy	--	January 1st, 2000


Displays a list of display elements that may be used in the clock format.


Forces the clock panel to a fixed width, regardless of format and choice of font.  This has no effect if the taskbar is attached to the left or right hand edge of the screen.


Chooses the foreground colour of the clock.


Chooses the background colour of the clock.


Uses the normal system colours for the clock panel.


Chooses a font for the clock.


Displays the name of the selected font.


Uses the normal system font for the clock, which is usually the same as the font used for menus.


Enables customisation of the tooltip, which appears when the cursor pauses over the clock panel for a few seconds.


Determines the tooltip format, which appears when the cursor pauses over the clock panel for a few seconds.

The tooltip format comprises a number of display elements representing various types of information.  Type the desired format string or click “Format Elements” to pick display elements from a list.


Displays a list of display elements that may be used in the tooltip format.


Causes the tooltip to remain visible as long as the cursor is over the clock panel.  Otherwise Windows hides it after a few seconds.


The copy/paste feature copies a custom format onto the clipboard when activated.  It may be subsequently pasted into another application.

Alternatives are to simply use the clock or tooltip format.


The copy/paste feature copies the clock format onto the clipboard when activated.  It may be subsequently pasted into another application.

Alternatives are to use the tooltip format or choose a custom format.


The copy/paste feature copies the tooltip format onto the clipboard when activated.  It may be subsequently pasted into another application.

Alternatives are to use the clock format or choose a custom format.


Determines the custom format that will be copied to the clipboard when the copy/paste feature is activated.

The format string comprises a number of display elements representing various types of information.  Type the desired format string or click “Format Elements” to pick display elements from a list.


Displays a list of display elements that may be used in the copy/paste feature’s custom format.


The selected days are highlighted on the calendar with a different colour.


The calendar window stays in the same position on the screen each time it is activated, instead of always returning to the default position.


The calendar closes automatically when another window is activated.


The calendar stays on top of all other windows, even when another window is in the foreground.

This option has little effect if “Close when not active” is checked.


Includes week numbers on the calendar.

Week numbers are determined according to the ISO8601 standard.


The calendar opens to the same month and year that was previously visible, instead of always starting with the present date.


Determines the day on which calendar weeks will begin.

This option does not affect the determination of week numbers, which are based on the ISO8601 standard.  ISO8601 weeks always begin on Mondays.


Chooses a font for the calendar.


Determines the action triggered by a single left-click on the clock panel.

Windows default	No effect for a single click.
Do nothing	No effect.
TClockEx Properties	Opens the properties window.
Calendar	Opens the popup calendar window.
Copy	Activates the copy/paste feature.


Determines the action triggered by a double left-click on the clock panel.

Windows default	Adjust date/time.
Do nothing	No effect.
TClockEx Properties	Opens the properties window.
Calendar	Opens the popup calendar window.
Copy	Activates the copy/paste feature.


Paints a fancy banner down the side of the context menu.


Prevents users from accessing the properties or exiting TClockEx, by removing certain options from the context menu and disabling the control panel icon.

See here for more information about security issues.


All new menu items are added to the top of the standard context menu provided by Windows.  If this option not selected, some items will be added to the bottom of the menu instead.

In versions prior to 1.4.2, this option was known as “Alternative menu order”, and the logic was reversed.


Enables the monitoring of CPU usage.  This must be checked if the CPU usage display element is used.

CPU usage monitoring requires the presence of the Windows System Monitor applet, which may be installed from the Windows 95/98 CD-ROM if necessary.

CPU usage monitoring is not possible on Windows NT/2000.


Displays CPU usage continuously as a coloured line above the clock, running from 0% to 100% usage.

CPU usage monitoring requires the presence of the Windows System Monitor applet, which may be installed from the Windows 95/98 CD-ROM if necessary.

CPU usage monitoring is not possible on Windows NT/2000.


Chooses the colour of the CPU usage indicator line.

CPU usage monitoring requires the presence of the Windows System Monitor applet, which may be installed from the Windows 95/98 CD-ROM if necessary.

CPU usage monitoring is not possible on Windows NT/2000.


Displays memory load continuously as a coloured line below the clock, running from 0% to 100% load.

Memory load is an evaluation of the operating system’s overall use of memory, including both physical RAM and virtual memory on disk.

On Windows NT/2000 systems, only physical RAM is included in the evaluation.


Memory load values are determined only from the operating system’s use of physical RAM, instead of both RAM and virtual memory on disk.

This option affects both the memory load indicator line and the memory load display element.

On Windows NT/2000 systems this option is always used.


Chooses the colour of the memory load indicator line.


Activates an icon named “Clock” in the Windows control panel that will activate the properties window when double-clicked.

This option is not available if the control panel module is not installed.


Adds an instruction to the system registry that causes TClockEx to load automatically as part of the Windows boot-up sequence.

Do not put a shortcut into the Startup menu if this option is checked, otherwise two instances of TClockEx will be started each time, with undesirable side-effects.


Shuts TClockEx down and restores the original taskbar clock.


Connects to the TClockEx home page on the Internet if possible.


Starts the default email client, if possible, and creates a new message to the author.


Saves the chosen settings and closes the window.


Restores the previous settings and closes the window.


Displays the help file.